/**
 * IOptions.java
 * Copyright (C) 2011 Yuanyan<yuanyan.cao@gmail.com>
 * 
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; version 2 of the License.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * For information on how to redistribute this software under
 * the terms of a license other than GNU General Public License
 * contact yuanyan.cao@gmail.com
 */
package edu.rabbit.table;


import edu.rabbit.DbEncoding;
import edu.rabbit.DbException;
import edu.rabbit.kernel.ILimits;
import edu.rabbit.kernel.DbUtility;

/**
 * Database options.
 * 
 * @author Yuanyan<yanyan.cao@gmail.com>
 * 
 * 
 */
public interface IOptions {

    /**
     * Name of system property for default encoding.
     */
    String DB_DEFAULT_ENCODING_PROPERTY = "DB_DEFAULT_ENCODING";

    /**
     * Default encoding.
     */
    DbEncoding DB_DEFAULT_ENCODING = DbUtility.getEnumSysProp(DB_DEFAULT_ENCODING_PROPERTY,
            DbEncoding.UTF8);

    /**
     * Name of system property for legacy file format support.
     */
    String DB_LEGACY_FILE_FORMAT_PROPERTY = "DB_LEGACY_FILE_FORMAT";

    /**
     * Legacy file format support.
     */
    boolean DB_LEGACY_FILE_FORMAT = DbUtility.getBoolSysProp(DB_LEGACY_FILE_FORMAT_PROPERTY, true);

    /**
     * Name of system property for default file format.
     */
    String DB_DEFAULT_FILE_FORMAT_PROPERTY = "DB_DEFAULT_FILE_FORMAT";

    /**
     * Default file format.
     */
    int DB_DEFAULT_FILE_FORMAT = DbUtility.getIntSysProp(DB_DEFAULT_FILE_FORMAT_PROPERTY,
            DB_LEGACY_FILE_FORMAT ? ILimits.DB_MIN_FILE_FORMAT : ILimits.DB_MAX_FILE_FORMAT);

    /**
     * File format of schema layer.
     * 
     * @return the fileFormat
     */
    int getFileFormat() throws DbException;

    /**
     * Set file format. It's allowed only on new empty data base. It can't be
     * performed in active transaction.
     * 
     * @param fileFormat
     * @throws DbException
     */
    void setFileFormat(int fileFormat) throws DbException;

    // Pragmas to modify library operation

    /**
     * Use freelist if false. Autovacuum if true.
     * 
     * @return the autovacuum
     */
    boolean isAutovacuum() throws DbException;

    /**
     * Set autovacuum flag. It's allowed only on new empty data base. It can't
     * be performed in active transaction.
     * 
     * @param autovacuum
     * @throws DbException
     */
    void setAutovacuum(boolean autovacuum) throws DbException;

    /**
     * Incremental-vacuum flag.
     * 
     * @return the incrementalVacuum
     */
    boolean isIncrementalVacuum() throws DbException;

    /**
     * Set incremental vacuum flag. It's allowed only on new empty data base. It
     * can't be performed in active transaction.
     * 
     * @param incrementalVacuum
     * @throws DbException
     */
    void setIncrementalVacuum(boolean incrementalVacuum) throws DbException;

    /**
     * Size of the page cache.
     * 
     * @return the pageCacheSize
     */
    int getCacheSize() throws DbException;

    /**
     * Set page cache's size. It can be performed only in active transaction.
     * 
     * @param pageCacheSize
     * @throws DbException
     */
    void setCacheSize(int pageCacheSize) throws DbException;

    // case_sensitive_like
    // count_changes
    // default_cache_size

    /**
     * Db text encoding.
     * 
     * @return the encoding
     */
    DbEncoding getEncoding() throws DbException;

    /**
     * Set encoding. It's allowed only on new empty data base. It can't be
     * performed in active transaction.
     * 
     * @param dbEncoding
     * @throws DbException
     */
    void setEncoding(DbEncoding dbEncoding) throws DbException;

    // full_column_names
    // fullfsync
    // incremental_vacuum
    // journal_mode
    // journal_size_limit

    /**
     * Checks if legacy file format is used for the new databases.
     */
    boolean isLegacyFileFormat() throws DbException;

    /**
     * Instructs Rabbit to use legacy file format for all new databases.
     */
    void setLegacyFileFormat(boolean flag) throws DbException;

    // locking_mode
    // page_size
    // max_page_count
    // read_uncommitted
    // reverse_unordered_selects
    // short_column_names
    // synchronous
    // temp_store
    // temp_store_directory

    // Pragmas to query the database schema

    // collation_list
    // database_list
    // foreign_key_list
    // freelist_count
    // index_info
    // index_list
    // page_count
    // table_info

    // Pragmas to query/modify version values

    /**
     * Schema cookie. Changes with each schema change.
     * 
     * @return the schemaCookie
     */
    int getSchemaVersion() throws DbException;

    /**
     * Set schema version. It can be performed only in active transaction.
     * 
     * @param version
     * @throws DbException
     */
    void setSchemaVersion(int version) throws DbException;

    /**
     * Change SchemaCookie. It can be performed only in active transaction
     */
    void changeSchemaVersion() throws DbException;

    /**
     * Verify schema cookie and return true if it is unchanged by other process.
     * 
     * If throwIfStale is true then throw exception if cookie is changed by
     * other process.
     * 
     * @param throwIfStale
     * @return true of schema has not been changed
     * 
     * @throws DbException
     */
    boolean verifySchemaVersion(boolean throwIfStale) throws DbException;

    /**
     * The user cookie. Used by the application.
     * 
     * @return the userCookie
     */
    int getUserVersion() throws DbException;

    /**
     * Set user's cookie. It can be performed only in active transaction.
     * 
     * @param userCookie
     * @throws DbException
     */
    void setUserVersion(int userCookie) throws DbException;

    // Pragmas to debug the library

    // integrity_check
    // quick_check
    // parser_trace
    // vdbe_trace
    // vdbe_listing
}
